#lang scribble/doc
@(require scribble/eval
          "shared.rkt"
          (for-label (except-in scribble/manual link)
                     scribble/eval))

@title[#:tag "reference-style"]{@;{Scribbling Documentation}Scribble文档}

@;{This section describes good style for Racket documentation writing.}
本节描述了Racket文档写作的良好风格。

@section{@;{Prose and Terminology}文字与术语}

@;{In the descriptive body of @racket[defform], @racket[defproc], etc.,
do not start with ``This ...'' Instead, start with a sentence whose
implicit subject is the form or value being described (but only start
the first sentence that way). Capitalize the first word. Thus, the
description will often start with ``Returns'' or ``Produces.''  Refer
to arguments and sub-forms by name.}
在@racket[defform]、@racket[defproc]等的描述体中，不要以“This…”开头，而是以一个隐含主语是所描述的表或值的句子开头（但只能以这种方式开始第一个句子）。把第一个字大写。因此，描述通常以“Returns”或“Produces”开头。按名称引用参数和子表。

@;{Do not use the word ``argument'' to describe a sub-form in a syntactic
form; use the term ``sub-form'' instead, reserving ``argument'' for
values or expressions in a function call.  Refer to libraries and
languages as such, rather than as ``modules'' (even though the form to
typeset a library or language name is called @racket[racketmodname]).
Do not call an identifier (i.e., a syntactic element) a ``variable''
or a ``symbol.'' Do not use the word ``expression'' for a form that is
a definition or might be a definition; use the word ``form,'' instead.
Prefer ``function'' to ``procedure.''}
不要用“argument（参数）”一词来描述句法表的子表；而要用“sub-form（子表）”一词，在函数调用中为值或表达式保留“argument”。以这种方式引用库和语言，而不是“modules（模块）”（尽管排版库或语言名称的表称为@racket[racketmodname]）。不要将标识符（即语法元素）称为“variable（变量）”或“symbol（符号）”。不要将“expression（表达式）”一词用于定义或可能是定义的表；而应使用“form（表）”一词。更倾向于“function（函数）”而不是“procedure（过程）”

@;{Use the word ``list'' only when you mean a run-time value consisting
of the empty list and cons cells; use the word ``sequence'' in other
cases, if you must use any word. For example, do not write that
@racket[begin] has a ``list of sub-forms;'' instead, it has a
``sequence of sub-forms.'' Similarly, do not refer to a ``list of
arguments'' in a function call; just write ``arguments'' if possible,
or write ``sequence of argument expressions.''  (Unfortunately,
``@tech[#:doc '(lib
"scribblings/reference/reference.scrbl")]{sequence}'' has acquired a
specific run-time meaning, too, but the collision is less severe than
the historical confusion between lists and other entities in Lisp.)}
仅当你指的是由空列表和组对（cons）单元格组成的运行时值时才使用“list（列表）”；在其他情况下，如果必须使用任何单词，请使用“sequence（序列）”。例如，不要写@racket[begin]有一个“list of sub-forms（子表列表）”；相反，它有一个“sequence of sub-forms（子表序列）”。类似地，不要在函数调用中引用“list of
arguments（参数列表）”；如果可能只写“arguments（参数）”，或者写“sequence of argument expressions（参数表达式序列）”。（不幸的是，@tech[#:doc '(lib
"scribblings/reference/reference.scrbl")]{sequence}获得了一个特定的运行时含义，同样，但这种冲突的严重性不如Lisp中列表和其他实体之间的历史混淆严重。）

@;{Avoid cut-and-paste for descriptive text. If two functions are
similar, consider documenting them together with
@racket[deftogether]. To abstract a description, consider using
explicit prose abstraction, such as ``@racket[x] is like @racket[y],
except that ...,'' instead of abstracting the source and instantiating
it multiple times; often, a prose abstraction is clearer to the reader
than a hidden abstraction in the document implementation.}
避免对描述性文本进行剪切和粘贴。如果两个函数相似，请考虑将它们与@racket[deftogether]一起记录。要抽象描述，请考虑使用显式的文字抽象，例如“@racket[x] is like @racket[y],
except that ...（@racket[x]类似于@racket[y]，除了……）”，而不是抽象源代码并多次实例化它；通常，文字抽象对读者来说比文档实现中的隐藏抽象更清晰。

@;{Hyphenate the words ``sub-form'' and ``sub-expression.''}
将单词“sub-form”和“sub-expression”使用连字符

@;{Use ``Windows,'' ``Mac OS,'' and ``Unix'' for the three
``platforms'' (as opposed to ``systems'') on which Racket runs. Use
``Unix'' as a generic term for Unix-like operating systems---notably
including Linux---other than Mac OS. Use ``Unix'' even when ``Gtk''
or ``the X11 windowing system'' would be more precisely correct, but
use ``X11'' as adjective when necessary, such as ``X11 display.''
Racket runs ``on'' a platform, as opposed to ``under'' a platform.}
在Racket运行的三个“平台”（而不是“系统”）上使用“Windows”、“Mac OS”和“Unix”。使用“Unix”作为类Unix操作系统的通用术语——特别是包括除Mac OS以外的Linux。即使“Gtk”或“X11窗口系统”更准确，仍然使用“Unix”，但在必要时使用“X11”作为形容词，如“X11显示”。Racket在“平台上”运行，而不是“平台下”运行。

@;{Avoid using a predicate as a noun that stands for a value
satisfying the predicate. Instead, use @racket[tech] and
@racket[deftech] to establish a connection between an
English word or phrase that describes the class of values
and the predicate (or
@tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{
 contract}). For example, avoid ``supply a
@racket[path-string?]''; prefer ``supply a
@tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{
 path or string}.''}
避免将判断（predicate）用作表示满足判断的值的名词。相反，使用@racket[tech]和@racket[deftech]在描述值类的英语单词或短语与判断（或@tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{
 合约（contract）}）之间建立连接。例如，避免“提供@racket[path-string?]“；更倾向于”提供@tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{
 路径或字符串（path or string）}


@section{@;{Typesetting Code}排版代码}

@;{Use @racketidfont{id} or a name that ends @racketidfont{-id} in
@racket[defform] to mean an identifier, not @racketidfont{identifier},
@racketidfont{variable}, @racketidfont{name}, or
@racketidfont{symbol}. Similarly, use @racketidfont{expr} or something
that ends @racketidfont{-expr} for an expression position within a
syntactic form. Use @racketidfont{body} for a form (definition or
expression) in an internal-definition position---always followed by 
@racket[...+] in a grammar description. Do not use
@racketidfont{expr} for something that isn't exactly an expression,
@racket[id] for something that isn't exactly an identifier, etc.;
instead, use @racket[defform/subs] to define a new non-terminal.}
使用@racketidfont{id}或以@racketidfont{-id}结尾的名称，在@racket[defform]中表示标识符，而不是@racketidfont{标识符（identifier）}、@racketidfont{变量（variable）}、@racketidfont{名称（name）}或@racketidfont{符号（symbol）}。类似地，使用@racketidfont{expr}或以@racketidfont{-expr}结尾的东西作为语法表中的表达式位置。在语法描述中，对位于内部定义位置的表（定义或表达式）使用@racketidfont{body}，后跟@racket[...+]。不要对不完全是表达式的东西使用@racketidfont{expr}，对不完全是标识符的东西使用@racket[id]，等等；而是使用@racket[defform/subs]来定义一个新的非终端。

@;{Beware of using @racket[deftogether] to define multiple variants of a
syntactic form or procedure, because each @racket[defform] or
@racket[defproc] creates a definition point, but each form or
procedure should have a single definition point. (Scribble issues a
warning when a binding has multiple definition points.) Instead, use
@racket[defproc*] or @racket[defform*].}
注意不要使用@racket[deftogether]来定义语法表或过程的多个变体，因为每个@racket[defform]或@racket[defproc]都创建一个定义点，但是每个表或过程都应该有一个定义点。（Scribble在绑定具有多个定义点时发出警告。）请改用@racket[defproc*]或@racket[defform*]。

@;{For function arguments, use @racket[v] as the meta-variable for ``any
value.'' Use @racket[x] as a meta-variable only for numerical
values. Other conventions include @racket[lst] for a list and
@racket[proc] for a procedure.}
对于函数参数，使用@racket[v]作为“任意值”的元变量。使用@racket[x]作为仅用于数值的元变量。其他约定包括列表的@racket[lst]和过程的@racket[proc]。

@;{Pay attention to the difference between identifiers and meta-variables
when using @racket[racket], especially outside of @racket[defproc] or
@racket[defform]. Prefix a meta-variable with @litchar{_}; for
example,}
在使用@racket[racket]时，请注意标识符和元变量之间的区别，特别是在@racket[defproc]或@racket[defform]之外。用@litchar{_}在元变量前面加上前缀，例如，

@verbatim[#:indent 2]|{@racket[(rator-expr rand-expr ...)]}|

@;{would be the wrong way to refer to the grammar of a function call,
because it produces @racket[(rator-expr rand-expr ...)], where
@racketidfont{rator-expr} and @racketidfont{rand-expr} are
typeset as variables. The correct description is}
引用函数调用的语法是错误的，因为它产生@racket[(rator-expr rand-expr ...)]，其中@racketidfont{rator-expr}和@racketidfont{rand-expr}被设置为变量。正确的描述是

@verbatim[#:indent 2]|{@racket[(_rator-expr _rand-expr ...)]}|

@;{which produces @racket[(_rator-expr _rand-expr ...)], where
@racketidfont{rator-expr} and @racketidfont{rand-expr} are typeset as
meta-variables. The @racket[defproc], @racket[defform], @|etc| forms
greatly reduce this burden in descriptions, since they automatically
set up meta-variable typesetting for non-literal identifiers. In
@racket[defform], be sure to include literal identifiers (i.e., those
not meant as variables, other than the form name being defined) in a
@racket[#:literals] clause.}
它产生@racket[(_rator-expr _rand-expr ...)]，其中@racketidfont{rator-expr}和@racketidfont{rand-expr}被设置为元变量。@racket[defproc]、 @racket[defform]、@|etc|表大大减少了这种描述负担，因为它们自动为非文本标识符设置元变量排版。在@racket[defform]中，确保在一个@racket[#:literals]子句中包含文本标识符（即那些不是作为变量的标识符，而不是定义的表名称）。

@;{To typeset an identifier with no particular interpretation---syntax,
variable, meta-variable, etc.---use @racket[racketidfont] (e.g., as in
@racketidfont{rand-expr} above).  Otherwise, use @racket[litchar],
not merely @racket[racketfont] or @racket[verbatim], to refer to a
specific sequence of characters.}
要在没有特定解释语法、变量、元变量等的情况下键入标识符，请使用@racket[racketidfont]（例如，在上面的@racketidfont{rand-expr}中）。否则，请使用@racket[litchar]，而不仅仅是@racket[racketfont]或@racket[verbatim]来引用特定的字符序列。

@;{When a syntactic form synthesizes an identifier from a given
identifier, use a combination of @racket[racketidfont] and
@racket[racket] to describe the identifiers. For example, if
@racket[_id] is combined with @racketidfont{is-} and @racketidfont{?}
to form @racketidfont{is-}@racket[_id]@racketidfont{?}, then implement
that identifier as
@code[#:lang "at-exp racket"]|{@racketidfont{is-}@racket[id]@racketidfont{?}}|.}
当句法表从给定的标识符合成标识符时，使用@racket[racketidfont]和@racket[racket]的组合来描述标识符。例如，如果@racket[_id]与@racketidfont{is-}及@racketidfont{?}组合来组成@racketidfont{is-}@racket[_id]@racketidfont{?}，然后将该标识符实现为@code[#:lang "at-exp racket"]|{@racketidfont{is-}@racket[id]@racketidfont{?}}|。

@;{When using @racket[defform] to describe a syntactic form, don't
confuse the @racket[#:contracts] clause with a grammar
specification. Use @racket[#:contracts] only for expressions within the
syntactic form, and the contract is a run-time constraint---not a
syntactic constraint, such as requiring a sub-form to be an identifier.
Use @racket[defform/subs] for syntactic constraints.}
使用@racket[defform]描述句法表时，不要将@racket[#:contracts]子句与语法规范混淆。使用@racket[#:contracts]仅用于语法表内的表达式，合约是运行时约束，而不是语法约束，例如要求子表是标识符。对语法约束使用@racket[defform/subs]。

@;{When showing example evaluations, use the REPL-snapshot style:}
显示示例计算时，请使用REPL快照样式：
@verbatim[#:indent 2]|{
  @examples[
   (+ 1 2)
  ]
}|

@;{See also the @racketmodname[scribble/example] library and 
@secref["examples-style"].}
另请参见@racketmodname[scribble/example]库和@secref["examples-style"]。

@;{Use four dots, @litchar{....}, in place of omitted code, since
@litchar{...} means repetition.}
用四个点@litchar{....}代替省略的代码，因为@litchar{...}意味着重复。


@section{@;{Typesetting Prose}排版文字}

@;{Refrain from referring to documentation ``above'' or ``below,'' and
instead have a hyperlink point to the right place.}
不要引用“上面”或“下面”的文档，而是使用指向正确位置的超链接。

@;{In prose, use @litchar{``} and @litchar{''} quotation marks instead of
@litchar{"}. Use @litchar{---} for an em dash, and do not include
spaces on either side. Use American style for quotation marks and punctuation
@; [Eli] BTW, I've asked several people about this, and the general
@;   agreement that I've seen is that this is a rather arbitrary rule
@;   and there's no harm in doing the more logical thing of putting
@;   the punctuations outside quotations and parens.  Just like you
@;   did at the end of this sentence...
@; [Matthew] See intro of this section.
at the end of quotation marks (i.e., a sentence-terminating period
goes inside the quotation marks). Of course, this rule does not apply
for quotation marks that are part of code.}
在文字中，用@litchar{``}和@litchar{''}引号代替@litchar{"}。使用@litchar{---}表示短破折号，两边不包括空格。在引号结尾处使用美式引号和标点符号（即引号内有句尾句点）。当然，这条规则不适用于作为代码一部分的引号。

@;{Do not use a citation reference (as created by @racket[cite]) as a
noun; use it as an annotation.}
不要将引文引用（由@racket[cite]创建）用作名词；将其用作注释。

Do not start a sentence with a Racket variable name, since it is
normally lowercase. For example, use ``The @racket[_thing] argument
is...'' instead of ``@racket[_thing] is...''
不要用Racket变量名开始一个句子，因为它通常是小写的。例如，使用“The @racket[_thing] argument
is...”而不是“@racket[_thing] is...”

Use @racket[etc] for ``@|etc|'' when it does not end a sentence, and
include a comma after ``@|etc|'' unless it ends a sentence of is
followed by other punctuation (such as a parenthesis).
当它不结束一个句子时，用@racket[etc]来表示“@|etc|”，并且在“@|etc|”后面加一个逗号，除非它结束一个句子，后面跟着其他标点符号（如括号）。

@section{@;{Section Titles}节标题}

@;{Capitalize all words except articles (``the,'' ``a,'' etc.),
prepositions, and conjunctions that are not at the start of the title.}
将除冠词（“the”、“a”等）、介词和连接词（不在标题开头）以外的所有单词大写。

@;{A manual title should normally start with a suitable keyword or key
phrase (such as ``Scribble'' for this manual) that is in boldface. If
the key word is primarily an executable name, use @racket[exec]
instead of @racket[bold]. Optionally add further descriptive text in
the title after a colon, where the text starting with the colon is not
in boldface.}
手册标题通常应以合适的黑体字关键字或关键短语（如本手册的“Scribble”）开头。如果关键字主要是可执行文件名，请使用@racket[exec]而不是@racket[bold]。（可选）在标题中冒号后添加更多描述性文本，其中以冒号开头的文本不是粗体。

@section{@;{Indexing}索引}

@;{Document and section titles, identifiers that are documented with
@racket[defproc], @racket[defform], etc. are automatically indexed, as
are terms defined with @racket[deftech].}
文档和节标题、使用@racket[defproc]、@racket[defform]等文档记录的标识符将自动编入索引，@racket[deftech]定义的术语也是如此。

@;{Symbols are not indexed automatically.  Use @racket[indexed-racket]
instead of @racket[racket] for the instance of a symbol that roughly
defines the use. For an example, try searching for ``truncate'' to
find @racket['truncate] as used with @racket[open-output-file]. Do not
use something like @racket[(index "'truncate")] to index a symbol,
because it will not typeset correctly (i.e., in a fixed-width font
with the color of a literal).}
符号不会自动编入索引。使用@racket[indexed-racket]，而不是@racket[racket]作为大致定义使用的符号的实例。例如，尝试搜索“truncate”以查找与@racket[open-output-file]一起使用的@racket['truncate]。不要使用类似@racket[(index "'truncate")]的东西来索引符号，因为它不会正确地排版（即，使用文本颜色的固定宽度字体）。

@;{Use @racket[index], @racket[as-index], and @racket[section-index] as a
last resort. Create index entries for terms that are completely
different from terms otherwise indexed. Do not try to index minor
variations of a term or phrase in an attempt to improve search
results; if search fails to find a word or phrase due to a minor
variation, then the search algorithm should be fixed, not the index
entry.}
使用@racket[index]、@racket[as-index]和@racket[section-index]作为最终手段。为完全不同于其他索引术语的术语创建索引项。不要试图索引某个词或短语的细微变化以改进搜索结果；如果由于细微变化而搜索无法找到某个词或短语，则应修复搜索算法，而不是索引项。

@section[#:tag "examples-style"]{@;{Examples}示例}

@;{Strive to include examples (using @racket[examples]) with the
documentation of every function and syntactic form. When writing
examples, refrain from using nonsense words like ``foo'' and ``bar.''
For example, when documenting @racket[member], resist the temptation
to write}
尽量在每个函数和语法表的文档中包含示例（使用@racket[examples]）。写示例时，不要使用“foo”和“bar”之类的无意义的词。例如，在为@racket[member]写文档时，要避免这样写

@interaction[
(member "foo" '("bar" "foo" "baz"))
]

@;{and instead write something like}
而要这样写

@interaction[
(member "Groucho" '("Harpo" "Groucho" "Zeppo"))
]
